IceLib Dependency Changes in CIC 4.0 2015R1

Starting in CIC 4.0 version 2015R1, some of IceLib's dependencies have changed. This article will cover the dependencies as of SU6 and how they changed in 2015R1.

Version Dependencies

In each of the sections below, the list of files was generated by creating a new project in Visual Studio, referencing only ININ.IceLib.dll (or ININ.IceLib-w64.dll for x64 projects). The IceLib documentation contains the explanation of 32 vs 64 bit IceLib.

SU6

The following table shows the files and versions pulled by the build. The key differences in the filenames are:

• The 64 bit libraries have "-w64" in the filename, as opposed to "-w32r" or no architecture indicator.
• The 32 bit libraries have dependencies that are named with "1-2" and file versions of 1.2.* and the 64 bit libraries have dependencies that are named with "1-3" and file versions of 1.3.*

 

2015R1 P3

The following table shows the files and versions pulled by the build. The key differences in the filenames are:

• The 64 bit libraries have "-w64" in the filename, as opposed to "-w32r" or no architecture indicator.
• Note that unlike the SU6 versions, both the 32 and 64 bit versions in 2015R1 use the 2.0.* versions of the dependent libraries

 

How Dependency Changes Impact Your Application

If you have an application that is currently running against SU6 or earlier, you'll be upgrading it to 2015R1 or later at some point. This section will discuss the changes that will have to be made during the upgrade.

Upgrading the application

The first step in upgrading the application is to update the project references in Visual Studio. If IceLib is referenced, it should look like one of the following screenshots:

To upgrade the references and recompile your project, perform the following steps:

1. Remove all IceLib references from the project by right clicking on each one and selecting remove. Take note of which libraries were referenced for later use.
2. Clean the project by right clicking on the project name and selecting Clean.
   
   Cleaning a project deletes all of the files from the project's bin directory. The reason this is necessary is to remove the old dependencies from the build directory.
3. Repeat the previous step for each build configuration (debug, release, etc.)
4. Verify that all of the IceLib DLLs and their dependencies have been removed from the build directories. If any remain, delete them manually.
5. Add references to the latest IceLib DLLs for your architecture
6. Build the project
7. Verify that the IceLib and dependendent DLLs in the output directory are the correct (new) version

Note: It is required that the application be rebuilt to complete the upgrade; it is not sufficient to simply copy/paste the new IceLib DLLs and dependent DLLs into your application's deployment directory. Because of the way .NET handles references in compiled executables, if the assembly name changes, the application must be recompiled so that it references the new assembly names.

Validating the Upgraded Application

Of course, the simplest way to validate that an application works after an upgrade is to run it and see if it works. However, to validate that the new files are in place, see the screenshots below. The output directories are the result of building the projects with the noted version of IceLib referenced. All 2015R1 versions are using Patch 3

Deployment

The IceLib documentation discusses two ways to deploy IceLib applications. Upgrading to 2015R1 or later will impact each of these in the following way:

Deploying using IceLib's redistributable merge module (MSM)

If your application's installer makes use of the IceLib MSM, simply update your installer package to use the new MSM for your architecture (IceLib_Redistributable_32bit.msm for x86 and IceLib_Redistributable_64bit.msm for x64) so that your application is deployed with the IceLib libraries of the same version that it was built against.

Deploying using the "copy file" method

When using the "copy file" method, the consumer of the project's output directory (could be a 3rd party installer technology, like WIX or InstallShield, or just copy/pasting the files) will need to retrieve the new files from the build and use the new filenames and versions. In the steps defined above to upgrade the application, cleaning the project removed the old files from the build directory and recompiling the project pulled in the new files that will need to be used.

Other Considerations

Upgrading Without Recompiling

Because the dependencies in IceLib did not change from 4.0 GA through SU6, it was possible to "upgrade" the IceLib version used by the application simply by copying the new DLLs into an application's working directory to overwrite the old versions. This could have also been accomplished by deploying the application without any IceLib libraries or the MSM and then installing the IceLib SDK onto the machine and having the application manually resolve the IceLib references from the SDK's installation path. While both of these methods for upgrades would typically be successful, they are not recommended or officially supported; as a general .NET development best practice, applications should be rebuilt whenever upgrading any referenced libraries or dependencies. Unlike COM libraries that have interfaces that are registered on the system (like ININ's old Client COM API), .NET libraries are typically not installed independently of the application using them and they are not registered with the system. Because of this, the typical deployment model for .NET applications is to include all of the referenced and dependent libraries in its distribution. The suggested deployment models in the IceLib documentation describe doing this by using the MSM and the "copy file" method.

Atypical Deployment Strategies

For applications that follow atypical .NET deployment strategies and dynamically find and load references from locations other than their deployment directory, it will be necessary for those applications to account for differences in library names and dependencies and handle those changes robustly when transitioning to 2015R1. The easiest method for doing this will likely be to maintain seperate versions for GA through SU6 and 2015R1 and later. If a single application is required, using the Reflection tools in .NET, it is possible for an application to fully control manually and explicitly loading libraries and resolving dependencies. Manual dependency resolution is often pretty tricky and may require rearchitecting the application to support dynamically loading components, but .NET provides the tools to do it if there are no other options.

IceLib and CIC Server Version Compatibility

As a general best practice, the IceLib version used by an application should match the CIC server version. However, IceLib versions are reverse compatible with CIC, with the exception of API constructs that are marked as obsolete or have explicit version caveats in the API documentation. This allows for applications to be built against the latest version of IceLib and still work with earlier CIC versions, with the aforementioned caveats. This applies to 2015R1 as well. The 2015R1 release is still only an update for CIC 4.0, not a major or minor version change, so reverse compatibility with the 4.0 version is maintained; breaking API changes are typically only released in major or minor CIC releases (e.g. CIC 4.1 or 5.0). To tie in to the previous consideration about dynamically resolving references to support old IceLib versions, it would typically be preferable to maintain a single application for 4.0 that uses the latest IceLib version.​​